---
title: Instale e Configure Astro
description: 'Como instalar Astro e começar a trabalhar em um novo pojeto.'
i18nReady: true
---
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

O [comando CLI `create astro`](#instale-com-o-assistente-cli) é a maneira mais rápida de começar um novo projeto Astro do zero. Ele o guiará por cada etapa de configurar o seu novo projeto Astro e permitirá que você escolha alguns modelos iniciais oficiais diferentes.

Ou você pode iniciar seu projeto [usando algum tema existente ou modelo inicial](#use-um-tema-ou-um-modelo-inicial).

Para instalar Astro manualmente, veja nosso [guia passo-a-passo de instalação manual](#instalação-manual).

:::tip[Prévias online]
Você prefere experimentar Astro em seu navegador? Visite [astro.new](https://astro.new/) para navegar por nossos modelos iniciais e comece um novo projeto Astro sem mesmo sair do seu navegador.
:::

## Pré-requisitos

- **Node.js** - `v18.17.1`, `v20.3.0` ou maior. ( `v19` não é suportada.)
- **Editor de texto** - Recomendamos [VS Code](https://code.visualstudio.com/) com nossa [extensão oficial Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode).
- **Terminal** - Astro é accessado pela interface de linha de comando (CLI).

## Compatibilidade de navegador

Astro é construído com Vite que tem como alvo navegadores com suporte a JavaScript moderno por padrão. Para referência completa, você pode ver a [lista de versões de navegadores atualmente suportados por Vite](https://vite.dev/guide/build.html#browser-compatibility).

## Comece um novo projeto

### Instale com o assistente CLI

<Steps>
1. Execute o seguinte comando no seu terminal para iniciar o nosso útil assistente de instalação:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # cria um novo projeto com npm
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # cria um novo projeto com pnpm
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # cria um novo projeto com yarn
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>

    Você pode executar `create astro` em qualquer lugar de sua máquina, então não há a necessidade de criar um novo diretório vazio para seu projeto antes de você começar. Se você não tiver um diretório vazio ainda para o seu projeto, o assistente ajudará a criá-lo automaticamente.

    Se tudo correr bem, você verá uma mensagem de sucesso seguida por alguns passos recomendados. Agora que seu projeto foi criado, você pode executar `cd` no seu novo diretório de projeto para começar a usar Astro.

2. Se você pulou o passo `npm install` durante o assistente CLI, então certifique-se de instalar as dependências antes de continuar.

3. Você agora pode [iniciar o servidor de desenvolvimento Astro](#inicie-o-servidor-de-desenvolvimento-astro) e ver a visualizacão em tempo real do seu projeto enquanto você constrói!
</Steps>

### Use um tema ou um modelo inicial

Você também pode começar um projeto Astro baseado em um [exemplo oficial](https://github.com/withastro/astro/tree/main/examples) ou com a branch `main` de qualquer repositório GitHub passando o argumento `--template` ao comando `create astro`.

<Steps>
1. Explore nossa [vitrine de temas e modelos](https://astro.build/themes/) onde você pode procurar temas para blogs, portfólios, sites de documentação, páginas iniciais e mais! Ou [procure no GitHub](https://github.com/search?o=desc&q=astro+starter&s=stars&type=Repositories) por ainda mais projetos iniciais.

2. Execute o seguinte comando no seu terminal, substituindo o nome do modelo inicial oficial Astro, ou o nome de usuário e repositório no GitHub com o tema que você quer usar:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # cria um novo projeto com um exemplo oficial
      npm create astro@latest -- --template <example-name>

      # cria um novo projeto baseado na branch main de um repositório GitHub
      npm create astro@latest -- --template <github-username>/<github-repo>
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # cria um novo projeto com um exemplo oficial
      pnpm create astro@latest --template <example-name>
      
      # cria um novo projeto baseado na branch main de um repositório GitHub
      pnpm create astro@latest --template <github-username>/<github-repo>
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # cria um novo projeto com um exemplo oficial
      yarn create astro --template <example-name>
      
      # cria um novo projeto baseado na branch main de um repositório GitHub
      yarn create astro --template <github-username>/<github-repo>
      ```
      </Fragment>
    </PackageManagerTabs>

    Por padrão, esse comando usará a branch `main` do repositório de modelo. Para usar um nome de branch diferente, passe como parte do argumento `--template`: `<github-username>/<github-repo>#<branch>`.


3. Responda as perguntas e siga as instruções do assistente CLI.

4. Você agora pode [iniciar o servidor de desenvolvimento Astro](#inicie-o-servidor-de-desenvolvimento-astro) e ver a visualizacão em tempo real do seu projeto enquanto você deixa ele com sua cara!
</Steps>

## Edite seu projeto

Para fazer mudanças em seu projeto, abra a pasta do seu projeto em seu editor de código. Trabalhar no modo de desenvolvimento com o servidor de desenvolvimento rodando permite que você veja atualizações no seu site conforme você edita o código.

Você pode também [personalizar aspectos do seu ambiente de desenvolvimento](#configure-seu-ambiente-de-desenvolvimento) como configurar TypeScript ou instalar as extensões de editor oficiais Astro.

### Inicie o servidor de desenvolvimento Astro

Astro vem com um servidor de desenvolvimento embutido que possui tudo que você precisa para desenvolver projetos. O comando CLI `astro dev` iniciará o servidor de desenvolvimento local para que você possa ver seu novo website em ação pela primeiríssima vez.

Todo modelo de projeto inicial vem com um script pré-configurado para executar `astro dev` por você. Depois de navegar até o diretório do seu projeto, use seu gerenciador de pacotes favorito para executar esse comando e iniciar o servidor de desenvolvimento Astro.

<PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
  npm run dev
  ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
  pnpm run dev
  ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
  yarn run dev
  ```
      </Fragment>
    </PackageManagerTabs>


Se tudo correr bem, Astro agora servirá seu projeto em [http://localhost:4321/](http://localhost:4321/). Visite esse link no seu navegador e veja seu novo site!

### Trabalhe em modo de desenvolvimento

Astro verificará por mudanças em seus arquivos em tempo real no seu diretório `src/` e atualizará a prévia do seu site conforme você constrói, assim você não precisa reiniciar seu servidor quando mudanças são realizadas durante o desenvolvimento. Você será sempre capaz de ver uma versão atualizada do seu site no navegador quando o servidor de desenvolvimento estiver rodando.

Ao ver seu site no navegador, você terá acesso a [barra de ferramentas de desenvolvimento Astro](/pt-br/guides/dev-toolbar/). Conforme você constrói, ela ajudará você a inspecionar suas [ilhas](/pt-br/concepts/islands/), detectar problemas de acessibilidade e mais.

Se você não é capaz de abrir seu projeto no navegador depois de iniciar o servidor de desenvolvimento, volte ao terminal onde você executou o comando `dev` e verifique a mensagem mostrada. Ela deverá dizer se algum erro aconteceu, ou se seu projeto está sendo servido em uma URL diferente do que [http://localhost:4321/](http://localhost:4321/).

### Configure seu ambiente de desenvolvimento

Explore os guias abaixo para personalizar a sua experiência de desenvolvimento.

<CardGrid>
  <LinkCard
    title="Configuração do Editor"
    description="Personalize seu editor de código para melhorar a experiência de desenvolvedor Astro e descobrir novas funcionalidades."
    href="/pt-br/editor-setup/"
  />
  <LinkCard
    title="Barra de Ferramentas de Desenvolvimento"
    description="Explore as funcionalidades úteis da barra de ferramentas de desenvolvimento."
    href="/pt-br/guides/dev-toolbar/"
  />
</CardGrid>

### TypeScript no Astro

Astro vem com suporte embutido para [TypeScript](https://www.typescriptlang.org/), que pode ajudar a prevenir erros em tempo de execução ao definir as formas de objetos e componentes no seu código.

Você não precisa escrever código TypeScript em seus projetos Astro para se beneficiar dele. Astro sempre trata o código do seu componente como TypeScript, e a [Extensão VSCode Astro](/pt-br/editor-setup/) inferirá o quanto possível para fornecer preenchimento automático, dicas e erros em seu editor.

<ReadMore>Leia mais sobre usar e configurar [TypeScript no Astro](/pt-br/guides/typescript/)</ReadMore>

## Construa e pré-visualize seu site

Para conferir a versão do seu site que será criada no momento de build, saia do servidor de desenvolvimento (<kbd>Ctrl</kbd> + <kbd>C</kbd>) e execute no terminal o comando de build apropriado para o seu gerenciador de pacotes:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm run build
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm build
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn run build
      ```
      </Fragment>
    </PackageManagerTabs>

Astro fará a build de uma versão do seu site pronta para distribuição em uma pasta separada (`dist/` por padrão) e permitirá que você assista o progresso pelo terminal. Isso alertará você sobre quaisquer erros de build no seu projeto antes de você distribuir em produção. Se o TypeScript é configurado com `strict` ou `strictest`, o script `build` também verificará por erros de tipo em seu projeto.

Quando a build é finalizada, execute o comando `preview` apropriado (como `npm run preview`) em seu terminal e você poderá visualizar a versão construída do seu site localmente na mesma janela de navegação de pré-visualização.

Note que isso pré-visualiza seu código que existia quando o comando build foi executado pela última vez. Isso tem a intenção de lhe dar uma prévia de como seu site parecerá quando ele for [distribuído na web](#distribua-seu-novo-site). Qualquer mudança futura que você realizar no seu código depois da build **não** será refletida na pré-visualização do seu site até que você execute o comando de build novamente.

Use (<kbd>Ctrl</kbd> + <kbd>C</kbd>) para sair da pré-visualização e execute outro comando de terminal, como reiniciar o servidor de desenvolvimento ou voltar a [trabalhar no modo de desenvolvimento](#trabalhe-em-modo-de-desenvolvimento) que fará atualizações conforme você edita para mostrar uma prévia em tempo real das mudanças no seu código.

<ReadMore>Leia mais sobre [a CLI Astro](/pt-br/reference/cli-reference/) e os comandos de terminal que você usará conforme você constrói com Astro.</ReadMore>

## Distribua seu novo site

Você pode querer [distribuir seu site imediatamente](/pt-br/guides/deploy/) antes de você começar a adicionar ou mudar muito código. Isso é útil para ter uma versão mínima e funcional do seu site publicada, e pode fazer você poupar tempo e esforços futuramente diagnosticando problemas na distribuição.

## Próximos passos

Successo! Agora você está pronto para começar a construir com Astro! 🥳

Aqui estão algumas coisas que recomendamos explorar a seguir. Você pode ler em qualquer ordem. Você pode até sair da nossa documentação e se divertir com seu novo projeto Astro, voltando aqui a qualquer momento que você encontrar problemas ou que tiver uma pergunta.


### Explore Funcionalidades do Astro

<CardGrid>
  <LinkCard
    title="Entenda sua base de código"
    description="Aprenda mais sobre a estrutura de arquivos Astro em nosso guia de Estrutura de Projeto."
    href="/pt-br/basics/project-structure/"
  />
  <LinkCard
    title="Crie coleções de conteúdo"
    description="Adicione conteúdo ao seu novo site com validação frontmatter e segurança de tipos automática."
    href="/pt-br/guides/content-collections/"
  />
    <LinkCard
    title="Adicione transições de visualização"
    description="Crie transições de página e animações perfeitas."
    href="/pt-br/guides/view-transitions/"
  />
  <LinkCard
    title="Aprenda sobre Ilhas"
    description="Leia sobre a arquitetura de ilhas Astro."
    href="/pt-br/concepts/islands/"
  />
</CardGrid>

### Faça o tutorial introdutório

Construa um blog Astro completamente funcional a partir de uma simples página em branco em nosso [tutorial introdutório](/pt-br/tutorial/0-introduction/).

Essa é uma ótima maneira de ver como Astro funciona e guiar você pelos básicos de páginas, layouts, componentes, roteamento, ilhas e mais. Ele também inclui uma unidade opcional e amigável para iniciantes e para aqueles mais novos nos conceitos gerais de desenvolvimento web, que guiarão você em instalar as aplicações necessárias em seu computador, criar uma conta no GitHub, e distribuir seu site.

## Instalação Manual

Esta explicação guiará você pelos passos de instalar manualmente e configurar um novo projeto Astro.

Se você preferir não usar nossa ferramenta CLI automática `create astro`, você pode configurar seu projeto por si mesmo ao seguir os passos abaixo.

<Steps>
1. Crie seu diretório

    Crie um diretório vazio com o nome do seu projeto, e navegue até ele.

    ```bash
    mkdir my-astro-project
    cd my-astro-project
    ```

    Uma vez que você estiver em seu novo diretório, crie seu arquivo de projeto `package.json`. Isso é como você gerenciará as dependências do seu projeto, incluindo Astro. Se você não é familiarizado com esse formato de arquivo, execute o seguinte comando para criar um.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm init --yes
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm init 
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn init --yes
      ```
      </Fragment>
    </PackageManagerTabs>

2. Instale Astro

    Primeiro, instale as dependências do projeto Astro dentro do seu projeto.

    :::note[Importante]
    Astro deve ser instalado localmente, não globalmente. Certifique-se de que você **não** está executando `npm install -g astro` `pnpm add -g astro` ou `yarn add global astro`.
    :::

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install astro
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add astro
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add astro
      ```
      </Fragment>
    </PackageManagerTabs>

    Então, substitua qualquer item gerado na seção "scripts" do seu `package.json` com o seguinte:

    ```json title="package.json" del={2} ins={3-6}
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "start": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },
    ```

    Você poderá usar esses scripts depois no guia para iniciar e rodar diferentes comandos Astro.

3. Crie sua primeira página

    No seu editor de texto, crie um novo arquivo no seu diretório em `src/pages/index.astro`. Esta será a sua primeira página Astro no projeto.

    Para esse guia, copie e cole o seguinte trecho de código (incluindo os traços `---`) em seu novo arquivo:

    ```astro title="src/pages/index.astro"
    ---
    // Bem-vindo ao Astro! Todo código entre esses três traços
    // é o "frontmatter de componente". Ele nunca executa no navegador.
    console.log('Isso executa em seu terminal, não no navegador!');
    ---
    <!-- Abaixo está seu "modelo de componente". É apenas HTML, mas com
        um toque de mágica para ajudar você a construir modelos excelentes. -->
    <html>
      <body>
        <h1>Olá, Mundo!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>
    ```

4. Crie seu primeiro recurso estático

    Você também desejará criar um novo diretório `public/` para armazenar seus recursos estáticos. Astro sempre incluirá esses recursos em sua build final para que você possa referenciá-los com segurança dentro dos seus modelos de componente.

    No seu editor de texto, crie um novo arquivo no seu diretório em `public/robots.txt`. `robots.txt` é um arquivo simples que a maioria dos sites incluirá para falar aos robôs de busca, como o Google, sobre como tratar seu site.

    Para esse guia, copie e cole o seguinte trecho de código em seu novo arquivo:

    ```diff title="public/robots.txt"
    # Exemplo: Permita que todos os robôs verifiquem e indexem seu site.
    # Sintaxe completa: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
    ```

5. Crie `astro.config.mjs`

    Astro é configurado usando `astro.config.mjs`. Este arquivo é opcional se você não quiser configurar o Astro, mas você pode querer criá-lo agora.

    Crie `astro.config.mjs` na raiz do seu projeto, e copie e cole o código abaixo nele:

    ```js title="astro.config.mjs"
    import { defineConfig } from 'astro/config';

    // https://astro.build/config
    export default defineConfig({});
    ```

    Se você desejar incluir [componentes de framework UI](/pt-br/guides/framework-components/) como React, Svelte, etc. ou usar outras ferramentas como Tailwind ou Partytown em seu projeto, aqui é onde você [importará e configurará as integrações manualmente](/pt-br/guides/integrations-guide/).

    Leia a [API de referência de configuração](/pt-br/reference/configuration-reference/) Astro para maiores informações.

6. Adicione suporte TypeScript

    TypeScript é configurado usando `tsconfig.json`. Mesmo que você não escreva código TypeScript, esse arquivo será importante para que ferramentas como Astro e VS Code saibam como entender seu projeto. Algumas funcionalidades (como npm package imports) não são completamente suportados no editor sem um arquivo `tsconfig.json`. 

    Se você pretende escrever código TypeScript, usar o modelo Astro `strict` ou `strictest` é recomendado. Você pode ver e comparar as três configurações de modelo em [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/).

    Crie `tsconfig.json` na raiz do seu projeto, e copie e cole o código abaixo nele. (Você pode usar `base`, `strict`, ou `strictest` para seu modelo TypeScript):

    ```json title="tsconfig.json" "base"
    {
      "extends": "astro/tsconfigs/base"
    }
    ```

    Leia o [guia de instalção TypeScript](/pt-br/guides/typescript/#setup) Astro para mais informações.

7. Próximos Passos

    Se você seguiu os passos acima, o diretório do seu projeto deve estar parecendo com o seguinte:

    <FileTree>
    - node_modules/
    - public/
      - robots.txt
    - src/
      - pages/
        - index.astro
    - astro.config.mjs
    - package-lock.json ou `yarn.lock`, `pnpm-lock.yaml`, etc.
    - package.json
    - tsconfig.json
    </FileTree>

8. Você agora pode [iniciar o servidor de desenvolvimento Astro](#inicie-o-servidor-de-desenvolvimento-astro) e ver uma prévia em tempo real do seu projeto enquanto você constrói!

</Steps>
